/*
 * Copyright (C) 2006 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.content;

import android.view.KeyEvent;

/**
 * 
 */
public interface DialogInterface {    
    /**
     * 肯定按钮的标识符。
     */
    public static final int BUTTON_POSITIVE = -1;

    /**
     * 否定按钮的标识符。
     */
    public static final int BUTTON_NEGATIVE = -2;

    /**
     * 中性按钮的标识符。
     */
    public static final int BUTTON_NEUTRAL = -3;

    /**
     * @deprecated Use {@link #BUTTON_POSITIVE}
     */
    @Deprecated
    public static final int BUTTON1 = BUTTON_POSITIVE;

    /**
     * @deprecated Use {@link #BUTTON_NEGATIVE}
     */
    @Deprecated
    public static final int BUTTON2 = BUTTON_NEGATIVE;

    /**
     * @deprecated Use {@link #BUTTON_NEUTRAL}
     */
    @Deprecated
    public static final int BUTTON3 = BUTTON_NEUTRAL;
    
    public void cancel();

    public void dismiss();

    /**
     * 用于允许对话框的创建者在对话框被取消时运行一些代码的接口。
     * 只有当对话框被取消时，他的意志才会被调用，如果创作者需要知道它什么时候被解散，那么使用{@link DialogInterface.OnDismissListener}.
     *
     */
    interface OnCancelListener {
        /**
         * 这个方法将在对话框被取消时被调用。
         * 
         * @param dialog 被取消的对话框将被传入该方法。
         */
        public void onCancel(DialogInterface dialog);
    }

    /**
     * 用于允许对话创建者在对话被解除时运行一些代码的接口
     */
    interface OnDismissListener {
        /**
         * 该方法将在对话框关闭时调用。
         * 
         * @param dialog 被解散的对话框将被传入该方法。
         */
        public void onDismiss(DialogInterface dialog);
    }

    /**
     * 用于允许对话框的创建者在显示对话框时运行一些代码的接口
     */
    interface OnShowListener {
        /**
         * 显示对话框时将调用此方法。
         *
         * @param dialog 显示的对话框将被传递到方法中。
         */
        public void onShow(DialogInterface dialog);
    }

    /**
     * 用于允许对话框的创建者在单击对话框上的项目时运行一些代码的接口
     */
    interface OnClickListener {
        /**
         * 当单击对话框中的按钮时，将调用此方法。
         * 
         * @param dialog The dialog that received the click.
         * @param which ：被点击的按钮（例如{@link DialogInterface#BUTTON1}）或该项目的位置被点击。
         */
        /* TODO: API理事会之后更改为使用BUTTON POSITIVE */
        public void onClick(DialogInterface dialog, int which);
    }
    
    /**
     * 用于在单击多选对话框中的项目时允许对话创建者运行某些代码的接口
     */
    interface OnMultiChoiceClickListener {
        /**
         * 当单击对话框中的项目时，将调用此方法。
         * 
         * @param dialog ：选择的对话框。
         * @param which 该项目在被点击的列表中的位置
         * @param isChecked 如果点击选中了该项目，则为true，否则为false。
         */
        public void onClick(DialogInterface dialog, int which, boolean isChecked);
    }
    
    /**
     * 将关键事件分派到此对话框时调用回调的接口定义。 在将键盘事件赋予对话框之前，将调用回调。
     */
    interface OnKeyListener {
        /**
         * 当一个键被分派到一个对话框时调用。 这使听众有机会在对话之前做出回应。
         * 
         * @param dialog 密钥已被分派到的对话框。
         * @param keyCode 被按下的物理键码
         * @param event 包含关于事件的完整信息的关键事件对象。
         * @return 如果侦听器已消耗该事件，则为true，否则为false。
         */
        public boolean onKey(DialogInterface dialog, int keyCode, KeyEvent event);
    }
}
